From 67c1600ac257cdac6430434852c42b671ead6ca2 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 14 Sep 2020 20:28:44 -0400
Subject: [PATCH] Document some API as widget-implementation only

Using gtk_widget_insert_before on a complex container
is a *bad* idea; it will mess up the containers bookkeeping
of its children and can easily lead to failure and crashes.
---
 gtk/gtkwidget.c | 36 ++++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 2775d66388..df99bc01d2 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -11156,6 +11156,8 @@ gtk_widget_observe_controllers (GtkWidget *widget)
  *
  * Returns the widgets first child.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's first child
  */
 GtkWidget *
@@ -11174,6 +11176,8 @@ gtk_widget_get_first_child (GtkWidget *widget)
  *
  * Returns the widgets last child.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's last child
  */
 GtkWidget *
@@ -11192,6 +11196,8 @@ gtk_widget_get_last_child (GtkWidget *widget)
  *
  * Returns the widgets next sibling.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's next sibling
  */
 GtkWidget *
@@ -11210,6 +11216,8 @@ gtk_widget_get_next_sibling (GtkWidget *widget)
  *
  * Returns the widgets previous sibling.
  *
+ * This API is primarily meant for widget implementations.
+ *
  * Returns: (transfer none) (nullable): The widget's previous sibling
  */
 GtkWidget *
@@ -11229,12 +11237,18 @@ gtk_widget_get_prev_sibling (GtkWidget *widget)
  * @previous_sibling: (nullable): the new previous sibling of @widget or %NULL
  *
  * Inserts @widget into the child widget list of @parent.
- * It will be placed after @previous_sibling, or at the beginning if @previous_sibling is %NULL.
  *
- * After calling this function, gtk_widget_get_prev_sibling(widget) will return @previous_sibling.
+ * It will be placed after @previous_sibling, or at the beginning if
+ * @previous_sibling is %NULL.
  *
- * If @parent is already set as the parent widget of @widget, this function can also be used
- * to reorder @widget in the child widget list of @parent.
+ * After calling this function, gtk_widget_get_prev_sibling(widget) will
+ * return @previous_sibling.
+ *
+ * If @parent is already set as the parent widget of @widget, this function
+ * can also be used to reorder @widget in the child widget list of @parent.
+ *
+ * This API is primarily meant for widget implementations; if you are
+ * just using a widget, you *must* use its own API for adding children.
  */
 void
 gtk_widget_insert_after (GtkWidget *widget,
@@ -11265,12 +11279,18 @@ gtk_widget_insert_after (GtkWidget *widget,
  * @next_sibling: (nullable): the new next sibling of @widget or %NULL
  *
  * Inserts @widget into the child widget list of @parent.
- * It will be placed before @next_sibling, or at the end if @next_sibling is %NULL.
  *
- * After calling this function, gtk_widget_get_next_sibling(widget) will return @next_sibling.
+ * It will be placed before @next_sibling, or at the end if
+ * @next_sibling is %NULL.
+ *
+ * After calling this function, gtk_widget_get_next_sibling(widget)
+ * will return @next_sibling.
+ *
+ * If @parent is already set as the parent widget of @widget, this function
+ * can also be used to reorder @widget in the child widget list of @parent.
  *
- * If @parent is already set as the parent widget of @widget, this function can also be used
- * to reorder @widget in the child widget list of @parent.
+ * This API is primarily meant for widget implementations; if you are
+ * just using a widget, you *must* use its own API for adding children.
  */
 void
 gtk_widget_insert_before (GtkWidget *widget,
-- 
2.30.2